home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Collection of Tools & Utilities
/
Collection of Tools and Utilities.iso
/
comm
/
robo42_a.zip
/
SCRIPT.DOC
< prev
next >
Wrap
Text File
|
1992-07-23
|
72KB
|
1,888 lines
┬─┬─────┐
│ │ │
│ ├───┬─┘ ┌┬──┐ ┬┬─┐ ┌┬──┐ ┌┬──┐ ┌┬──┐ ┌┬─┬─┐ ┌┬─┬─┐ (tm)
│ │ │ ││ │ │├─┴┐ ││ │ ││ ││ │ ││ │ │ ││ │ │
┴─┴ ┴── └┴──┘ ┴┴──┘ └┴──┘ └┴──┘ └┴──┘ ┴┴ ┴ ┴ ┴┴ ┴ ┴
┬ ┌┐ ┌──┬┐
The ultimate tool for unattended └──┤│ ┌┬─┴┘
BBS communications. └┘o└┴──┘
┌────────────────────────────┐
│ Script Language Reference │
└────────────────────────────┘
(c) Copyright 1992, Parsons Consulting
Table of Contents
ROBOCOMM 4.1 SCRIPT PROCESSING ............................... 1
INTRODUCTION ................................................. 1
SCRIPT COMMENTS .............................................. 1
DOCUMENTATION SYNTAX ......................................... 1
LABELS ....................................................... 2
MACROS ....................................................... 2
PARAMETERS ................................................... 3
SCRIPT COMMANDS .............................................. 4
CAPTURE "<cFile>" [OVERWRITE | APPEND] ....................... 4
CD "<cDirectory>" ............................................ 5
CLEAR [WATCHES] .............................................. 5
CLOSE ........................................................ 5
COPY "<cSource>" [TO "<cTarget>"] ............................ 6
DELAY <nSeconds> ............................................. 6
DISABLE <nWatch> ............................................. 7
DOWNLOAD ["<cFileSpec>"] [USING "<cProtocol>"] ............... 7
ENABLE <nWatch> .............................................. 8
ERASE "<cFile>" .............................................. 9
EXIT <nReturnVal> ............................................ 9
GOSUB <label> ................................................ 9
GOTO <label> ................................................ 10
HANGUP ...................................................... 10
IF [NOT] <condition> ["<argument>"] <command> ............... 11
EMPTY ....................................................... 11
EXIST ....................................................... 11
DAY ......................................................... 11
DIR ......................................................... 11
CONNECTED ................................................... 12
ERRORLEVEL .................................................. 12
IMPORT ["A"|"D"] "<cFile>" [EXISTONLY] ...................... 12
JOIN "<cConference>" ........................................ 13
MD "<cDirectory>" ........................................... 13
MESSAGE "<cString>" ......................................... 13
NOTES "<cFile>" ............................................. 14
PARAMETER [nNumber] "<cPrompt>" ............................. 14
- i -
Table of Contents
PASSWORD "<cPassword>" ...................................... 14
RD "<cDirectory>" ........................................... 14
RENAME "<cfile>" [TO] "<cNewName>" .......................... 15
RENUMBER "<cFile>" [<nCount>] ............................... 15
RETURN ...................................................... 15
RUN "<cDosCommand>" [KEYBOARD "<cKeyString>"] ............... 16
SEND "<cString>" ............................................ 20
SOUND <nFrequency> <nDuration> .............................. 21
STATISTICS "<cFile>" ........................................ 22
TERMINAL .................................................... 22
TIMEOUT <nSeconds> .......................................... 22
TITLE "<cString>" ........................................... 22
UPLOAD "<cFileSpec>" [USING "<cProtocol>"] .................. 23
VENUE <cVenueCode> .......................................... 23
WAITFOR "<cString>" [FAILURE <command>] ..................... 24
WAITUNTIL ["<cTime>"] ["<cDate>"] ........................... 25
WHEN "<cString>" <command> .................................. 25
- ii -
I. Robocomm 4.1 Script Processing
* INTRODUCTION
Robocomm's script processing system is a high level
interpreted language designed to extend the automation
capabilities of the software in instances where the
pre-defined "Agenda Items" do not perform the service
required.
If you have done any programming at all on the PC, even at
the batch file level, then Robocomm's script language
should be fairly intuitive and straight-forward. The
script commands are processed sequentially with the
ability to jump to "labels" like DOS batch files using
GOTO and GOSUB statements like BASIC programs.
Perhaps the most significant capability of the script
language is its ability to prompt the user for an
unlimited number of parameters from the agenda
creation/editing screen. This allows for a great deal of
flexibility in the creation of "generic" scripts that will
work on a wide variety of systems. At the time the
"Execute Script" agenda item is created, the script itself
asks the user to supply any needed information that is
specific to the script run, such as a door number or a
file name.
In addition, all of the prompt definitions and other
BBS-Specific information for each BBS can be accessed from
within the script, allowing the script author to limit the
amount of "hard coded" search text within the script.
What all of this means is that it is now possible for
people to create their own generic "agenda items" with
Robocomm's script language. These scripts can then be
distributed and run without modification by other Robocomm
users!
* SCRIPT COMMENTS
You may place non-executable descriptive text anywhere you
like within a script file, as long as it is on a line by
itself and is preceded by a semicolon.
* DOCUMENTATION SYNTAX
_________________________________________________________________
Robocomm 4.1 - Script Language Reference Page: 1
As you read through this documentation, places where a
command argument is to be entered by the script author are
indicated between angle brackets <like this>. Text
between angle brackets and also surrounded by quotation
marks indicates that the script author is to input a word
surrounded by quotation marks:
"<cFile>" --> "robocomm.cap"
Reserved Words (or COMMANDS) appear in all UPPER CASE.
Optional command arguments are surrounded by square
brackets [LIKE THIS]. When a choice between one or more
command arguments is required, all available options will
be listed, separated by the pipe symbol. Thus, an
optional command argument with three choices will look
like this:
[ SEVERAL | OPTIONAL | COMMANDS ]
* LABELS
Labels in Robocomm scripts are created by starting a line
with a colon character. Many script commands allow
command control to quickly jump forward or backward within
a script file be referencing a label name. Labels must be
on a line all by themselves. Robocomm will use all text
contained between the colon character and the first space
or end of line as the label name. The following are all
examples of valid label lines:
:ERROR (something must have gone wrong)
:start
:This-Is-An-Example-Of-A-Very-Long-Label-Indeed!
* MACROS
Most commands ask for text to be supplied as an argument.
Whenever that text is contained within quotes, several
"macros" can be used with specific meanings. All Robocomm
script macros are indicated by surrounding text by percent
signs. At script run-time, these macros will be replaced
with the appropriate text before being used by the
specified script command.
_________________________________________________________________
Robocomm 4.1 - Script Language Reference Page: 2
1. %ID% - Translated to the BBS ID of the currently
connected BBS.
2. %QWKDIR% - Translated to the configured download
directory for mail packets.
3. %REPDIR% - Translated to the configured directory for
outgoing replies.
4. %DLDIR% - Translated to the configured file download
directory.
5. %ULDIR% - Translated to the configured file upload
directory.
6. %DOW% - Translated to three characters indicating the
current day of the week: MON,TUE,WED,THU,FRI,SAT,SUN
7. %DOM% - Translated to two numeric characters indicating
the current day of the month. Range 01-31.
8. %MONTH% - Translated to three characters indicating the
current month:
JAN,FEB,MAR,APR,MAY,JUN,JUL,AUG,SEP,OCT,NOV,DEC
9. %NMONTH% Translated to two numeric characters
indicating the month of the year.
10. %YEAR% - Translated to 4 numeric characters indicating
the current year, e.g. 1991
11. %BBS##% - Translated to field number ## from the
Directory-BBS record for the currently connected BBS.
See Appendix "A" for a complete list of the BBS##
macros.
a) ## is the field from BBS40.DBF to return.
12. %P##% - Translated to the text parameter number ##,
which was entered by the user when he/she created the
currently running "execute script" agenda item.
13. %WC#% - Translated to Wildcat Command number #.
* PARAMETERS
With Robocomm, you can set up scripts which prompt the
user for input when an "Execute Script" agenda item is
_________________________________________________________________
Robocomm 4.1 - Script Language Reference Page: 3
being created. To do this, simply embed a statement
similar to the following in your script file:
PARAMETER "Enter your mother's maiden name:"
When the user is creating the agenda, Robocomm will pause
and ask the question specified between the quotes on the
parameter line. The user will be allowed to enter up to
128 characters of any type in response to the question.
To access the text input by the user, the script author
embeds %P##% into his/her script file at any location
where double quotes are to surround text. In the text
above, ## represents the parameter number you wish to
access.
Continuing our example, to send the user's mother maiden
name to the BBS you would use the following script
command:
SEND "%P1%
In the example above the number "1" is specified to access
the parameter text input in response to the first
PARAMETER statement which is contained in the file. It is
important to understand that Robocomm numbers the
parameters so that they correspond to the same order as
the PARAMETER statements within the text file. For a
working example of PARAMETERs, examine the file
SET_PCB.RS.
II. Script Commands
* CAPTURE "<cFile>" [OVERWRITE | APPEND]
Opens capture file <cFile> and closes any capture file
previously opened.
Options: If OVERWRITE is specified, then the contents of
any existing <cFile> will be replaced with the captured
data. If APPEND is specified
Defaults: <cFile> defaults to the current BBS ID with a
CAP extension. The file creation mode defaults to APPEND.
Example:
_________________________________________________________________
Robocomm 4.1 - Script Language Reference Page: 4
CAPTURE "\ROBOCOMM\LOGS\CHESSGAM.CAP" OVERWRITE
See Also:
CLOSE
* CD "<cDirectory>"
Changes the current DOS drive and/or directory to
<cDirectory>.
Note: The Robocomm home drive and directory is always
restored upon termination of script processing.
Note: If the specified directory does not exist, Robocomm
will make a log notation and abort the script processing.
Example:
CD "F:\TEMP\LISTS"
See Also:
MD
RD
* CLEAR [WATCHES]
Clears all text watches installed via the WHEN command.
Robocomm adds another watch item each time you issue the
WHEN command from within a script. Deactivating a watch
with the DISABLE command does not actually remove it from
the list of text items which are compared to all incoming
text. The CLEAR command should be used when you wish to
discard the entire "watch list." The next WHEN command
issued after a CLEAR will install watch #1.
See Also:
WHEN
WAITFOR
DISABLE
ENABLE
* CLOSE
_________________________________________________________________
Robocomm 4.1 - Script Language Reference Page: 5
Closes any open capture file started via the CAPTURE
command. If no capture file is currently active, the
command is ignored.
See Also:
CAPTURE
* COPY "<cSource>" [TO "<cTarget>"]
Copies the file <cSource> to <cTarget>. If <cSource>
cannot be opened or <cTarget> cannot be created a notation
will be made in ROBOCOMM.LOG and script processing will be
terminated. If <cTarget> already exists when the copy
begins, it will be replaced with the contents of
<cSource>. <cTarget> is optional, and if not specified,
Robocomm will attempt to create a file with the same name
as <cSource> in the current directory.
Note: Attempting to COPY a currently open log or capture
file is not possible and will result in the termination of
script processing.
Examples:
COPY "C:\ROBOCOMM\GROUPONE.CAP"
"C:\OLDCAPS\GROUPONE.CAP"
COPY "%QWKDIR%%ID%.PTR"
See Also:
ERASE
RENAME
* DELAY <nSeconds>
Pauses all script processing for <nSeconds>. No
characters are read from the active communications port.
Absolutely nothing happens, other than a not-so-dramatic
pause. Keep in mind that the BBS may still be sending
characters to Robocomm. If so, they will be stored in
Robocomm's internal communications buffer until the end of
the delay period.
Note: If you set a long delay period, keep in mind that
Robocomm may appear to be "frozen" to some users because
the timeout counter in the upper corner of the screen will
not update. If you are worried that some user may
_________________________________________________________________
Robocomm 4.1 - Script Language Reference Page: 6
over-react to this condition, consider placing a MESSAGE
command to place a notation in the lower log window before
the call to DELAY.
Example:
DELAY 10
* DISABLE <nWatch>
Temporarily disable a watch installed via the WHEN
command. The contents of watch number <nWatch> will not
be compared against incoming text during subsequent
WAITFOR processing. The watch may be reactivated later
with the ENABLE command.
Example:
DISABLE 5
See Also:
WHEN
WAITFOR
ENABLE
CLEAR WATCHES
* DOWNLOAD ["<cFileSpec>"] [USING "<cProtocol>"] [RESUMEOK |
OVERWRITE]
Downloads a file to <cFileSpec> using <cProtocol>.
<cFileSpec> may be a complete filename or a download path.
If the protocol you select is a batch protocol and the BBS
sends a file of a different name than that specified in
<cFileSpec>, Robocomm will attempt to rename the file to
the specified name after the download is complete.
<cFileSpec> defaults to the currently defined file
download directory.
USING "<cProtocol>" is an optional parameter which
specifies the protocol or batch file to use for the
transfer. All of Robocomm's internal protocols, "ZMODEM",
"YMODEM","YMODEM-G", "ASCII" are valid values for
<cProtocol>, as is the name any batch file which uses
Robocomm's standard method for communicating with batch
files.
_________________________________________________________________
Robocomm 4.1 - Script Language Reference Page: 7
<cProtocol> defaults to the currently defined file
download protocol.
If you are using Robocomm's internal ZMODEM protocol, you
may inform the protocol that it is OK to attempt to resume
an aborted transfer by adding the RESUMEOK directive to
the DOWNLOAD command line. The existing portion of the
file will be verified with the sending file and a resume
will be attempted if possible.
If you anticipate that the DOWNLOAD command will be
receiving a file which already exists, then you may
specify the OVERWRITE directive to replace the existing
file with the file being downloaded.
Examples:
DOWNLOAD
This command will use the currently defined file download
path and protocol to receive a file.
DOWNLOAD "%ULDIR%" USING "YMODEM-G"
Downloads files to your configured file upload directory
using Robocomm's internal Ymodem-G.
DOWNLOAD USING "ROBORH"
Downloads files to the default file download directory
using the HS/Link external batch protocol.
* ENABLE <nWatch>
Resume processing of a watch previously suspended with the
DISABLE command. If text read from the communications
port during a WAITFOR matches the contents of watch number
<nWatch> the previously indicated action will be executed.
Example:
ENABLE 3
See Also:
WAITFOR
_________________________________________________________________
Robocomm 4.1 - Script Language Reference Page: 8
WHEN
DISABLE
* ERASE "<cFile>"
Erases <cFile> from disk. No error is returned and script
processing will continue normally if <cFile> does not
exist. If <cFile> does exist, it will be deleted.
* EXIT <nReturnVal>
Quits script processing and returns to the agenda control
level. If <nReturnVal> is greater than zero, a notation
will be made in the log and the "Execute Script" agenda
item will be marked with an exclamation mark. The
exclamation mark implies an error, and will prevent the
agenda item from being deleted if it has "temporary"
status.
<nReturnVal> defaults to zero. If the script returns zero
to the agenda processing module, the task will be marked
as completed. This means that if the "Execute Script"
agenda item was temporary it will be removed from the
agenda on its next "re-set" operation.
* GOSUB <label>
Branches control flow to the line following the specified
<label>. Control will remain at the specified level until
a RETURN statement is encountered, at which time agenda
processing will resume with the first valid command line
immediately following the GOSUB statement. GOSUBs may be
nested 4096 levels deep.
Example:
The following script lines, would send "Robocomm 4.1" to
the BBS:
GOSUB firstpart
SEND "4.1"
:FIRSTPART
SEND "Robocomm "
RETURN
_________________________________________________________________
Robocomm 4.1 - Script Language Reference Page: 9
See Also:
GOTO
RETURN
* GOTO <label>
Pass the sauce. Spaghetti code lives! The ubiquitous
GOTO command will branch script control to the line
following the specified <label> and never look back.
It's up to you to keep track of where the program's going
when you use GOTOs.
Example: The following code produces an infinite loop,
from which Robocomm will never recover without a loving
keystroke from you.
:Label1
Send "Even robots can get "
GOTO Label3
:Label2
Send "Dizzy!!! |"
GOTO Label1
:Label3
Send "a little bit "
GOTO "Label2
NOTE: Pressing the F3 "Abort Agenda" or "F1" jump to
terminal keys during a runaway script are your escape
hatches in instances like these.
See Also:
GOSUB
Two Guys From Italy.
* HANGUP
Terminates the current connection by hanging up the modem.
Script processing continues after the disconnection with
the line following the hangup command. If a WAITFOR
command is issued subsequent to a disconnection, Robocomm
will assume that you did not intend to drop carrier and
will abort the current script.
_________________________________________________________________
Robocomm 4.1 - Script Language Reference Page: 10
* IF [NOT] <condition> ["<argument>"] <command>
Evaluates <condition> and executes the script command
<command> if it is true. The optional NOT parameter may
be added immediately following the keyword IF when you
want to execute <command> only when <condition> is not
true.
1. EMPTY
Use this command to test the existence of a parameter.
If a parameter is not passed (i.e. left blank on the
agenda editing screen), then EMPTY will be true.
Examples:
IF EMPTY "%P1%" GOTO ERROR
IF NOT EMPTY "%P2%" SEND "%P2%|"
2. EXIST
Use this test for the existence of a file.
Examples:
IF EXIST "C:\QWKS\GROUPONE.KEY" GOTO SENDKEY
IF NOT EXIST "%ID%.RLY" GOSUB GETMSGS
IF EXIST "ALLFILES.ZIP" RENAME "ALLFILES.ZIP" TO
"ALLFILES.OLD"
3. DAY
Robocomm can test today's day of week with the use of
any of these keywords.
Examples:
IF NOT DAY "SUN" GOTO WORK
IF DAY "SUN" GOTO CHURCH
IF DAY "MON" RENAME "BULL_1.CAP" TO "BULL_1.MON"
4. DIR
_________________________________________________________________
Robocomm 4.1 - Script Language Reference Page: 11
Use this option test for the existence of a
subdirectory on a disk.
Examples:
IF DIR C:\SCRIPTDIR\TEMP\ GOTO KILLDIR
IF NOT DIR \TEMP MD \TEMP
5. CONNECTED
Tests if the modem is currently connected with a BBS
system.
Examples:
IF CONNECTED SEND "BYE|"
IF NOT CONNECTED GOSUB CLEANUP
6. ERRORLEVEL
Tests to see is the last command executed with the RUN
command set an errorlevel greater than zero.
IF ERRORLEVEL GOTO TRYAGAIN
IF NOT ERRORLEVEL GOTO SUCCESS
7. YES
Checks to see if a parameter is equal to Y,y,YES,
Yes or yes.
IF YES "%P3%" GOTO SENDREP
* IMPORT ["A"|"D"] "<cFile>" [EXISTONLY]
This command allows you to import the <cFile> file listing
into Robocomm's "Available Files" or "Downloaded Files"
directory. The optional letter "A" or "D" tells Robocomm
which file directory to send the file names to. By
default Robocomm sends file listings to the "Available
Files" directory. The optional EXISTONLY clause tells
Robocomm to only import those files that can be located in
your configured download, upload or search directories.
Example:
IMPORT "D" "VAMPIRE.CAP" EXISTONLY
This command tells Robocomm to import VAMPIRE.CAP into the
"D"ownloaded files directory, adding only those files to
the directory that can be found in any of Robocomm's
configured search directories. NOTE: If you are
creating a file list in a script, you can use the
CONFSTAMP "<text>" script command to write the current
conference marker to the capture file.
_________________________________________________________________
Robocomm 4.1 - Script Language Reference Page: 12
IMPORT "GIFS.CAP"
This command tells Robocomm to import the file GIFS.CAP
into the available files directory.
* JOIN "<cConference>"
Attempts to join the conference specified, using the
prompts defined on the Directory-BBS-Prompts screen for
the currently connected BBS. Script processing is aborted
if the Join attempt is unsuccessful or cannot be verified.
Examples:
JOIN "0"
Attempts to navigate to the "Main Board" prompt.
JOIN "Robocomm"
Attempts to navigate to the "Robocomm Conference Command"
prompt.
* MD "<cDirectory>"
Attempts to create a subdirectory named <cDirectory>.
Note: If the specified directory cannot be created,
Robocomm will make a log notation and abort the script
processing.
Example:
MD "C:\TEMPDOWN"
See Also:
CD
RD
* MESSAGE "<cString>"
Posts <cString> as a message in ROBOCOMM.LOG.
_________________________________________________________________
Robocomm 4.1 - Script Language Reference Page: 13
* NOTES "<cFile>"
This command places the contents of <cFile> into
Robocomm's internal data structures so that the data can
be viewed later via Robocomm's "Notes" command on the
Directory-BBS screen.
NOTE: Robocomm will not import a file longer than 10,240
characters. Attempts to do so will be ignored.
Example:
NOTES "%ID%.NOT"
* PARAMETER [nNumber] "<cPrompt>"
Defines a parameter question that will be used to prompt
the user for input at agenda creation time. <cPrompt> may
be up to 40 characters in length. The user will be
allowed to input up to 128 characters.
NOTE: The optional nNumber argument is really only for
readability purposes and is not examined by Robocomm at
all. Robocomm numbers parameters sequentially, in the
order they are encountered within the script file.
Example:
PARAMETER "Heard any good jokes lately?"
* PASSWORD "<cPassword>"
Updates the password in the Directory-BBS record for the
current BBS with <cPassword>.
Example:
PASSWORD "NewPass"
* RD "<cDirectory>"
Attempts to remove subdirectory <cDirectory>. The
specified directory must be completely empty, with no
hidden files or subdirectories.
_________________________________________________________________
Robocomm 4.1 - Script Language Reference Page: 14
Note: If the specified directory cannot be removed,
Robocomm will make a log notation and abort the script
processing.
Example:
RD "C:\GONNER"
See Also:
CD
MD
* RENAME "<cfile>" [TO] "<cNewName>"
Attempts to rename <cFile> to <cNewName>. Just as with
DOS, this command will fail if a file names <cNewName>
already exists. The TO clause is optional, and functions
only to enhance readability.
* RENUMBER "<cFile>" [<nCount>]
Uses Robocomm's internal renumbering scheme to maintain a
<nCount> archived versions of <cFile>. <nCount>
defaults to 1 if not specified.
Example:
RENUMBER "VAMPIRE.CAP" 5
* RETURN
Causes script process control to return to the first valid
command line immediately following the most recent GOSUB
command.
Example:
IF SUN GOSUB GETFILES
SEND "BYE|"
EXIT 0
:GETFILES
MESSAGE "It's Sunday. Downloading and processing
Allfiles"
RENUMBER "%DLDIR%ALLFILES.ZIP" 2
_________________________________________________________________
Robocomm 4.1 - Script Language Reference Page: 15
SEND "D;ALLFILES.ZIP|"
DOWNLOAD
RETURN
* RUN "<cDosCommand>" [KEYBOARD "<cKeyString>"]
Shells to DOS and runs the command <cDosCommand>. If you
need to test the result of the called process, the
ERRORLEVEL set by the called program is retained by
Robocomm to be queried with the IF ERRORLEVEL script
command.
Note: Robocomm's current drive and directory is always
restored automatically after the called process returns
control.
Examples:
RUN "Rexclude c:\download"
CAUTION: If you do not plan on exploring the KEYBOARD
clause, detailed below, be sure not to call any process
from within Robocomm that will require a keypress. If you
do this and aren't around to manually press the required
key, Robocomm will be unable to recover and all processing
will halt until you show up to rectify the situation.
Using the KEYBOARD clause:
In cases where you really want to run an external program
that requires keystrokes, the optional KEYBOARD command
can help. This command stuffs the keyboard by temporarily
taking over BIOS interrupt 16h. Thus, you can automate
all or part of the program that you call with Robocomm's
RUN command.
This capability was inspired by a memory resident program
called Key-Fake by Charles Petzold and copyrighted by
Ziff-Davis Publishing Company. Mr. Petzold did an
excellent job and Robocomm imitates, with a few
enhancements, Mr. Petzold's method of defining the keys to
stuff the keyboard. The KEYBOARD command function works
with almost any programs you might want to call, except
for those rare programs that directly take over the
keyboard.
_________________________________________________________________
Robocomm 4.1 - Script Language Reference Page: 16
The KEYBOARD <cKeyString> is a character string parameter.
This character string can contain:
1) embedded character strings.
2) named keys within curly brackets.
3) the number 0 by itself.
4) the number 1 by itself.
1) Embedded character strings:
Characters within inner quotes (either single or double
quotes) are normal ASCII characters. KEYBOARD
"'EXIT'"would stuff the keyboard with the four keys 'E',
'X', 'I', and 'T'.
Normally, these characters are limited to those
alphabetical, numeric, and symbol characters that can be
typed at the keyboard. Keys such as <F1> and <Insert>
cannot be specified this way. You can specify other non-
keyboard characters such as graphics characters which are
not normally available from the keyboard.
If non- keyboard characters are specified, KEYBOARD will
attempt to pass them to the called program, but some
programs may not be able to accept them. Please note that
the character string passed to KEYBOARD begins and ends
with double quotes ("), and that the inner string begins
and ends with single quotes (').
2) Named keys within curly braces:
In order to specify keys such as <F1>, <Insert>, and
<Ctrl-A>, you must specify them within curly braces.
KEYBOARD can handle every possible key combination that
converts to a keycode. Some keys such as the
<PrintScreen> and <NumLock> have no keycode value and
cannot be stuffed with KEYBOARD.
When specifying the keys, case is not important. You may
use uppercase, lowercase, or mixed case. The keys are
specified with the form {[<switch>-]keyname} where keyname
is the name of the key optionally preceded by one of the
switch keys: <Shift>, <Ctrl>, <Alt>. Only one switch key
can be specified because they are mutually exclusive.
When more than one switch key is pressed at a time, the
_________________________________________________________________
Robocomm 4.1 - Script Language Reference Page: 17
<Ctrl> key overrides the <Shift> key and the <Alt> key
overrides the <Ctrl> key.
The following keys are valid:
{F1}..{F12}
{Shift-F1}..{Shift-F12}
{Ctrl-F1}..{Ctrl-F12}
{Alt-F1}..{Alt-F12}
Note that F11 and F12 are only available on enhanced
keyboards and may not be accepted by a program running on
a computer with a standard keyboard.
{Ctrl-A}..{Ctrl-Z}
{Alt-A}..{Alt-Z}
{Ctrl-0}..{Ctrl-9}
{Alt-0}..{Alt-9}
These keys correspond to the keys on both the numeric
keypad and the QWERTY keyboard when a standard keyboard is
in use. An enhanced keyboard can differentiate between
the numeric keypad and the QWERTY keyboard if the software
enables it to do so. If the software you're using
requires that the numbers come from the numeric keypad,
use the # symbol explained below.
{<Symbol>}
{Ctrl-<Symbol>}
{Alt-<Symbol>}
where <Symbol> is anyone of the 30+ symbols available on
the keyboard such as !@#$%&*~_-+={}[]|\:;"'<>,.?.
{Enter}, {Esc}, {Tab}, {Bksp}, {Space}
{Ctrl-Enter}..{Ctrl-Space}
{Alt-Enter}..{Alt-Space}
{Home}, {End}, {PgUp}, {PgDn}, {Left}, {Right}, {Up},
{Down}, {Ins}, {Del}
{Ctrl-Home}..{Ctrl-Del}
{Alt-Home}..{Alt-Del}
These keys are all found on the numeric keypad.
{*Home}, {*End}, {*PgUp}, {*PgDn}, {*Left}, {*Right},
{*Up}, {*Down}, {*Ins}, {*Del}
{Ctrl-*Home}..{Ctrl-*Del}
{Alt-*Home}..{Alt-*Del}
_________________________________________________________________
Robocomm 4.1 - Script Language Reference Page: 18
where the * symbol stands for the extra cursor control pad
available on enhanced keyboards. These keys can only be
specified when an enhanced keyboard is in use; these keys
are not available on a standard keyboard. Use these keys
when the software requires that the keypress be from the
extra cursor control pad.
{#0}..{#9}, {#.}, {#}, {#*}, {#-}, {#+}, {#Enter}
{Ctrl-#0}..{Ctrl-#9}, {Ctrl-#.}..{Ctrl-#Enter}
{Alt-#0}..{Alt-#9}, {Alt-#.}..{Alt-#Enter}
where the # symbol stands for the numeric keypad. These
keys can only be specified when an enhanced keyboard is in
use; a standard keyboard does not differentiate the
numeric keypad keys from their QWERTY keyboard
counterparts. Use these keys when the software requires
that the keypress be from the numeric keypad only.
{SysReq}
notice that the {SysReq} key is specified without the
{Ctrl-} prefix.
3) The number 0 by itself:
The number 0 by itself is a special symbol to KEYBOARD; it
tells the function to report back to the called program,
at that point, that the keyboard buffer is empty. This
should be unnecessary for most programs, but if you find
that at some point the called program seems to clear the
keyboard buffer or lose keystrokes, you may need to use a
0 to fool the program into thinking the keyboard buffer is
empty. By default, KEYBOARD stuffs a 0 key after each
keystroke. This makes the external program think that the
keyboard buffer is empty after each keystroke. This is
necessary because some programs clear the keyboard buffer
after each keystroke.
4) The number 1 by itself:
The number 1 by itself is also a special symbol to
KEYBOARD. It tells the function to wait for the user to
hit a key before continuing; the keystroke is then passed
directly to the external program. Obviously, this
capability has limited usefulness in an unattended
environment, but is useful when the user must make a
choice or enter a secret code before KEYBOARD can continue
stuffing more keys.
_________________________________________________________________
Robocomm 4.1 - Script Language Reference Page: 19
Summary:
All of these key definitions can be put in the same
character string. You are currently limited to stuffing
250 keystrokes into the keyboard. Some programs take over
the keyboard directly, which keeps Robocomm from stuffing
the keyboard. There is nothing that can be done about
these programs, but they are definitely in the minority.
Example:
Import Robocomm's TRANSFER.LOG into a dBASE database using
FoxPro:
RUN "foxproln" KEYBOARD "`USE TRANSFER.DBF` {ENTER} `APPE
FROM TRANSFER.LOG` {ENTER} `QUIT` {ENTER}"
In our doc file, that line wrapped to a second line, but
in your script file, it should be all on one line.
* SEND "<cString>"
This command sends one or more characters to the BBS.
Before sending the text, Robocomm will look for the
existence of two special characters; the pipe "|", the
carat "^" and the tilde "~". Use the pipe character
whenever you would like Robocomm to send a carriage
return. Use the carat to signify that the next character
is a "control character." Use the tilde whenever you
would like Robocomm to pause for on half second before
sending the next character.
Examples:
SEND "^X^X~~~~^X^X"
This example sends two "Control-X" characters, pauses for
2 seconds, and then sends another paid of Control-X
characters. This is the key sequence that is commonly
used to abort a file transfer.
SEND "B|1|"
This example sends the letter "B" followed by a carriage
return (ASCII code 13), followed again by the number 1 and
another carriage return.
_________________________________________________________________
Robocomm 4.1 - Script Language Reference Page: 20
NOTE: Robocomm does not automatically append a carriage
return to the text you specify between quotes. If a
carriage return is required, you must supply it by ending
the string with the | or ^M characters.
SENDING RESERVED CHARACTERS: To send a tilde, carat or
pipe character to the BBS as part of your send string,
simply place a carat before the character.
^^ sends ^
^~ sends ~
^| sends |
* SOUND <nFrequency> <nDuration>
Creates a sound on the PC's speaker.
<nFrequency> is a numeric value indicating the desired
frequency, in the range of 37 to 32767. If not specified,
<nFrequency> defaults to 500.
<nDuration> is the amount of time to continue the sound,
in 100ths of a second.
NOTE: If the user has the speaker style option on
Robocomm's General Configuration screen set to SILENT no
sound will be produced.
For the musical purists in the group, the following is a
table of values to produce standard musical pitches:
Pitch Frequency Pitch Frequency
----------------------------------------------------------
C 130.80 mid C 261.70
C# 138.60 C# 277.20
D 146.80 D 293.70
D# 155.60 D# 311.10
E 164.80 E 329.60
F 174.60 F 349.20
F# 185.00 F# 370.00
G 196.00 G 392.00
G# 207.70 G# 415.30
A 220.00 A 440.00
A# 233.10 A# 466.20
B 246.90 B 493.90
_________________________________________________________________
Robocomm 4.1 - Script Language Reference Page: 21
C 523.30
----------------------------------------------------------
* STATISTICS "<cFile>"
This command places the contents of <cFile> into
Robocomm's internal data structures so that the data can
be viewed later via Robocomm's "Statistics" command on the
Directory-BBS screen.
NOTE: Robocomm will not import a file longer than 10,240
characters. Attempts to do so will be ignored.
Example:
STATISTICS "%ID%.STS"
* TERMINAL [NOKEY] [EXITON "<text>"] [DOORWAY]
All parameters are optional. Their purposes are:
NOKEY - Bypasses the alarm and the necessity to press
a key after jumping to terminal.
NOTE: The terminal mode "alarm" is actually a
60 second timer that will enable Robocomm to
recover if no one is around to interact with
the terminal. Using the NOKEY clauses
disables this alarm, so Robocomm will jump to
terminal mode and will not go back to
automated processing until the user presses
Alt-X or when the EXITON text is seen. (See
below)
EXITON - This command allows you to specify a text
string that Robocomm will watch for whenever
it is in terminal mode. If Robocomm
encounters the specified text it will
immediately exit the terminal mode and resume
script processing.
DOORWAY - This command causes the terminal to start
with "Doorway" mode turned on.
NOTE: You will need to Press [Alt =] to turn
doorway mode off before you can exit with
Alt-X.
Examples:
TERMINAL
Goes into standard terminal mode, sounds alarm.
TERMINAL NOKEY
Goes into standard terminal with no alarm or keypress.
TERMINAL DOORWAY
Goes into Doorway mode terminal, sounds alarm.
TERMINAL EXITON "<EXIT>"
Goes into terminal. Automatically exits on <EXIT>.
TERMINAL NOKEY DOORWAY EXITON "<EXIT>"
You get the idea...
* TIMEOUT <nSeconds>
Sets the number of seconds that all subsequent WAITFOR
commands will allow to pass while they watch for their
intended string. If <nSeconds> elapses before the match
is found, control will pass to the defined WAITFOR FAILURE
clause, or, if none is defined, to the next executable
statement in the script.
Example:
TIMEOUT 30
See Also:
WAITFOR
* TITLE "<cString>"
Sets the script title that will appear in the Script
Selection window on the agenda modification screen.
_________________________________________________________________
Robocomm 4.1 - Script Language Reference Page: 22
Although this statement can appear anywhere within the
script file, you should place it as the first line in the
script, to make the Script Selection window pop-up as
rapidly as possible. It's also a good idea to indicate
the type of BBS system the script is designed to handle in
the title.
Example:
TITLE "(PCBoard) This is a script title example!"
* UPLOAD "<cFileSpec>" [USING "<cProtocol>"]
Sends <cFileSpec> to the BBS using <cProtocol>.
<cFileSpec> may be any valid path and/or filename,
including wildcard characters. If the optional USING
<cProtocol> clause is specified, then Robocomm will use
the protocol specified. By default Robocomm will attempt
to use configured file upload protocol. ASCII is a
valid upload protocol type.
Examples:
UPLOAD "c:\qwks\%ID%.KEY" USING "YMODEM-G"
UPLOAD "C:\OUTGOING\*.ZIP"
UPLOAD "message.txt" USING "ASCII"
* VENUE <cVenueCode>
Attempts to move to the area of the BBS system specified
by cVenueCode. Valid codes are:
Code Description Systems
-------- --------------------------------- -------
MSGS Go to the message sub-menu Wildcat
FILE Go to the file sub-menu Wildcat
MAIN Go to the Main Menu PCB/WC
MAIL Go to the defined QWK door PCB/WC
PRO Go to ProDoor PCB/Pro
Examples:
VENUE MAIL
VENUE MSGS
See also:
_________________________________________________________________
Robocomm 4.1 - Script Language Reference Page: 23
JOIN
* WAITFOR "<cString>" [FAILURE <command>]
Watches for incoming text matching <cString> while
simultaneously watching for any "watches" defined with the
WHEN command. The amount of time that Robocomm watches
for text is defined separately with the TIMEOUT command.
If <cString> is recognized within the allotted time,
Robocomm simply proceeds on to the next executable line in
the script. If, however, <cString> is not recognized,
Robocomm's subsequent behavior depends upon whether the
optional FAILURE clause has been specified. If a FAILURE
<command> has been specified, Robocomm will immediately
process <command>. If no FAILURE command is specified,
then an error message is inserted in the log and script
processing is terminated.
NOTE: Aside from the file transfer commands. WAITFOR is
the only script command which actually retrieves incoming
text from the comm port receive buffers. For this reason,
you will see text scrolling in the online window only
while a WAITFOR is being evaluated.
NOTE: To copy a list of the currently active watches to
the VERBOSE mode log in Robocomm, simply press [Alt-S]
while Robocomm is watching for text. This feature will
aid you greatly in debugging your scripts.
Examples:
The following script fragment sets up a number of watches
via the WHEN command and demonstrates the use of the
WAITFOR command in conjunction with them.
; A sample script to download ProDoor ZIPMail packets.
;
; FOR DEMONSTRATION PURPOSES ONLY -- NOT TESTED
;
TIMEOUT 10
WHEN "MORE?" SEND "N|"
WHEN "[ENTER] TO CONTINUE" SEND "|"
WHEN "SCAN MESSAGES" SEND "N|"
WAITFOR "COMMAND?" FAILURE GOTO ERROR
TIMEOUT 600
SEND "ZIPM|"
WHEN "NO MESSAGES" GOTO NOMAIL
WHEN "NOT ENOUGH TIME" GOTO ERROR
WHEN "PROTOCOL" SEND "Z|"
WAITFOR "CTRL-X ABORTS" FAILURE GOTO ERROR
_________________________________________________________________
Robocomm 4.1 - Script Language Reference Page: 24
RENUMBER "%QWKDIR%%ID%.ZPM" 5
DOWNLOAD "%QWKDIR%%ID%.ZPM"
EXIT 0
:ERROR
HANGUP
EXIT 1
; End of script.
See Also:
WHEN
TIMEOUT
* WAITUNTIL ["<cTime>"] ["<cDate>"]
Pauses script execution until a specified date and/or
time.
<cTime> is the time of day to start, in 24 hour format
HH:MM
<cDay> is the date to start in MM/DD/YY or MM-DD-YY
format.
Both parameters are optional, but at least one must be
specified. If <cDate> is not specified, it defaults to
the current date. If <cTime> is not specified, it
defaults to "00:00" (Midnight).
Examples:
WAITUNTIL "06:00"
WAITUNTIL "12:00" "12/13/91"
WAITUNTIL "12/01/91"
* WHEN "<cString>" <command>
Creates an incoming text watch for <cString> and executes
<command> whenever it is seen. WHEN commands are valuable
when prompts from the BBS may come in random order or when
a standardized response to a prompt should be sent
whenever a certain prompt is received from the BBS. It is
important to understand that the WHEN command merely posts
<cString> and <command> for evaluation by the WAITFOR
_________________________________________________________________
Robocomm 4.1 - Script Language Reference Page: 25
command. Thus, WHENs are only valid while a WAITFOR is
currently being evaluated.
Example:
See example under the WAITFOR command.
See Also:
WAITFOR
DISABLE
ENABLE
CLEAR
_________________________________________________________________
Robocomm 4.1 - Script Language Reference Page: 26
-----------------------
SCRIPT.DOC - APPENDIX A
-----------------------
Directory-BBS Field Macros
--------------------------
The following %BBS??% macros are all to non-prompt related items:
Macro # Description
------- ----------------------------------------------------
1 The BBS Robocomm/Mail ID. (duplicated by %ID%)
2 The BBS Name
3 Phone Number #1 \
4 Phone Number #2 |-- Dialing macros A-J NOT expanded.
5 Phone Number #3 /
7 Login Password
13 Login Name
17 Qmail Door Conference
19 File Upload Protocol
20 File Download Protocol
21 Mail Door Upload Protocol
22 Mail Door Download Protocol
60 PC-Pursuit outdial city
63 Command to Open Mail Door (Wildcat!) or Door Number/Name (PCBoard)
66 Upload area (Wildcat! only)
------------------------------------------------------------------------
The Following BBS?? Macros are the defined prompt definitions for
PCBoard Systems:
29 Language to use
30 Help prompt
31 Do you want graphics
32 More?
33 Scan Messages
34 Pause - "Enter to Continue"
35 Main Board Prompt
36 Confernce ID string (# translated to conference number)
37 Upload file description
38 No Protocol Defined
39 Start Transfer
40 Mail Door Main Command
41 Start Mail Download
42 Start Mail Upload
43 Packet Transfer Confirmation.
44 No Mail to Download
45 Enter First Name
46 Enter Password (logon)
47 Message Menu Prompt
48 Download File Not Found
49 Generic Command (usually "Command")
50 Duplicate Upload
51 Insufficient security to download (restricted access)
52 Not enough time/bytes to download.
53 Upload file not accepted
54 ProDoor: Enter Upload Description
55 <not in use>
56 ProDoor: Main Board Command
57 <not in use>
58 ProDoor: Start Transfer
59 Front End Prompt (Usually "DOOR #")
70 Front End Mail Program (Robo sends 2 ESC characters)
71 Not enough time to download mail
-----------------------------------------------------------------------
The Following BBS?? Macros are the defined prompt definitions for
Wildcat! Systems:
29 Read Bulletins?
30 View Mail?
31 Location Confirmation (are you xxxx from xxxx?)
32 Press Enter to Continue
33 Enter Birthday
34 Pause
35 Main Menu
36 Confernce ID string (# translated to conference number)
37 Upload file description
38 Bulletin Menu
39 Start File Download
40 Mail Door (TomCat) Command Prompt
41 Start Mail Download
42 Start Mail Upload
43 Packet Transfer Confirmation.
44 No Mail to Download
45 Enter First Name
46 Enter Password (logon)
47 Message Menu Prompt
48 File Name to Download
49 Read Newsletter?
50 Duplicate Upload
51 Upload file not a duplicate
52 Logon name failure
53 Start file upload
54 File Menu
55 Enter Last Name
56 Phone number confirmation
57 <not in use>
58 D/L File Found
59 Front End Prompt (Usually "DOOR #")
70 File Upload Rename
71 Extended Descriptions
72 File Keywords
73 Not Enough Time to Download Mail
74 Choose Upload Area
75 Not Enough Time to Download
76 Not Enough Bytes to Download
77 Not Enough Credit to Download
78 Password protect upload question
------------------------------------------------------------------------------
The following %WC?% macros are the defined commands for the currently
connected Wildcat BBS system:
Number Command Default
------ -------------------------------------------- -------
1 Quit from FILE or MESSAGE menu to MAIN menu. Q
2 Go to the MESSAGE menu from the MAIN menu. M
3 Go to the FILE menu from the MAIN menu. F
4 Start file download sequence D
5 Start file upload sequence U
6 "Info Scan" a downloadable file I
7 Start the new file scan sequence N
8 Log off from FILE, MESSAGE or MAIN menus. G
9 Start conference join sequence J
Example:
; Go to the file menu
SEND "%WC3%|"